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PREFACE 



The Library Management Facility (LMF) is an extension of the Interactive 
System Productivity Facility (ISPF) library concepts and options. It 
allows users to control the contents of their libraries and to manage 
their development processes. Libraries controlled by LMF are called 
"controlled libraries." 

This manual tells you how to create the LMF library controls and how the 
controlled libraries are used in the development process. It assumes 
that you are engaged in program development and are familiar with the 
operation of the ISPF/Program Development Facility in the MVS 
environment . 

Chapter 1 presents an overview of LMF, telling you: 

• What it is 

• What it will do for you 

• How it is structured 

• The terminology used. 

Chapter 2 describes how a library administrator administers the 
controlled library. To this end, it specifies how a library 
administrator: 

• Creates the library hierarchy 

• Defines the library controls 

• Maintains the libraries and the controls. 
Chapter 3 guides a user in: 

• Obtaining a member from a controlled library 

• Promoting a member into a controlled library 

• Promoting a member within a controlled library. 

LMF is part of the Program Development Facility (PDF) of the Interactive 
System Productivity Facility (ISPF). To understand and use LMF, you 
should be familiar with PDF and its operation as described in: 

• Interactive System Productivity Facility/Program Development 
Facility for MVS Program Reference , SC34-4024. 
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CHAPTER 1. INTRODUCTION 



This chapter presents an overview of the Library Management Facility 
(LMF) , which is a part of ISPF/PDF. At the conclusion of this chapter, 
you should be able to answer many questions about LMF, including: 

What is LMF? 

What will LMF do for me? 

How is LMF structured? 

What terminology will I need to know to use LMF? 



Definition of LMF 



The Library Management Facility is an optional extension of the ISPF 
library concepts and options. Before going into a discussion of LMF, 
let's take a brief look at what is meant by "library" and what an ISPF 
library is. 

A library is a repository for information. Information can be taken 
from the library and used in some manner. It may also be changed as a 
result of use or from additional data becoming available. The 
information can then be returned to the library, either unchanged or 
modified. 

A library must be organized so that information can be readily retrieved 
and returned to its rightful place. There must also be a mechanism to 
permit retrieval and replacement of information. 

An ISPF library is a collection of code or data units, called members. 
ISPF can have many libraries containing different types of information. 
However, any individual library generally contains members with the same 
type of information. Each library is a cataloged partitioned data set, 
with a 3- level name in the form: 

1 pro j ect -name . group -name . type ' 

where: 

• "project -name" is the common identifier for all libraries in the 
same project. 

• "group-name" identifies a particular set of libraries. 

• "type" identifies the type of information in the library, such as 
Assembler Source Code, COBOL programs, or SCRIPT files. 
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Note: The second- level qualifier has been changed from 
"library", as it was in the previous release of ISPF/PDF, to 
"group", to avoid any confusion that might arise from having a 
qualifier called "library" as part of an ISPF library name. 

A library member is identified as: 

1 pro j ect -name . group-name . type (member ) ' 



Libraries can be organized in a hierarchical manner. For example, 
members being developed or updated are generally in a development 
library. Those members that have been unit tested and are ready for 
integration testing can be moved up the hierarchy to a test library. 
Those members that have been completely tested can be moved up the 
hierarchy to a master library. 

For a discussion of the library structure, refer to ISPF/PDF for MVS 
Program Reference . 

LMF allows users to control the contents of their libraries and to 
manage their development processes. Libraries controlled by LMF are 
called controlled libraries. 

LMF controls determine who can: 

• Enter information into a controlled library 

• Get information from a controlled library to modify and return to 
the controlled library 

• Move information from one controlled library to another. 

In other words, the controls allow the user to determine who can 
manipulate library members. 

Note: RACF, or an equivalent protection system, is required in 
order to enforce the controls set by LMF. Without data 
protection, there is a high risk of damaging the integrity of the 
data. See ISPF and ISPF/PDF for MVS Installation and 
Customization for more information. 

One problem of importance in a development project is maintaining data 
integrity. LMF helps maintain integrity by ensuring that only one 
person can update a member at a time. In addition, LMF allows only 
those people authorized to update a member to update that member. It 
does this by allowing only authorized people to replace a member in a 
controlled library with an updated member. LMF also aids the 
development process in other ways, such as allowing authorized people to 
put a member into two or more hierarchies at once. 



2 ISPF/PDF for MVS Library Management 



MVS password protection cannot be used on libraries controlled by LMF, 
since the LMF -initiated task cannot know what the password is. You will 
get an error message if you attempt to use a password-protected library 
that LMF cannot handle. 

To use LMF, you will need a library administrator to set up the controls 
and maintain them. 



Library Structure 



LMF uses the same library concepts and structure as ISPF/PDF. In fact, 
LMF libraries are ISPF libraries. However, the libraries managed by LMF 
are controlled. The controls determine which members can be promoted 
and edit -locked. Promotion is the mechanism for moving a member to a 
controlled library, and for moving a member to higher levels within a 
controlled library. Edit -locking prevents more than one person at a 
time from updating a member in a controlled library. 

The following terminology applies to libraries controlled by LMF: 

Controlled Library An ISPF library that has been identified as a 

library to which users must have specific 
authority for access, for updates, and for 
promotion activities. 

Promotion The means by which a member is moved to a 

controlled library, or moved to higher levels 
within a controlled library. 

Promotion Hierarchy An ordered set of related controlled libraries 

that a member is promoted through during the 
development or maintenance process. 

Library Hierarchy A promotion hierarchy in which all the libraries 

have the same "type" qualifier. 

A collection of controlled libraries having a common project and group 
name is called a Controlled Group . A collection of controlled groups 
having a common project name is called a Controlled Project . 

Figure 1 illustrates a controlled project, ISPFEXAM. This project has a 
3-level hierarchical structure with four controlled groups, PROD, 
SYSTST, DEPT1, and DEPT2. Each controlled group has three controlled 
libraries, one each for PLI , MSGS, and LOAD. The libraries in group 
PROD, for example, are ISPFEXAM. PROD. PLI, ISPFEXAM. PROD. MSGS, and 
ISPFEXAM. PROD. LOAD. 

Promotion to the controlled project involves moving a member into an 
entry- level library: for example, into ISPFEXAM. DEPT2. PLI. Promotion 
within the controlled project involves moving a member from one level 
library to the next higher- level library of the same type. Thus, 
promotion of a member is within the library hierarchy. Promotion from 
ISPFEXAM.DEPT2.PLI is, for example, moving the member to the next level 
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in the hierarchy, to ISPFEXAM.SYSTST.PLI. We will look at promotion 
again later in this chapter. 

We will use the controlled libraries in Figure 1 in Chapters 2 and 3 to 
illustrate the operations available in LMF. 
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Figure 1. ISPF Controlled Project (ISPFEXAM) 
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Controls 



The controls that are available with LMF organize your libraries into a 
hierarchical structure. They also direct, guide, and restrain the 
movement of members into and out of controlled libraries. Controls are 
set up by the library administrator. More details on setting up 
controls are given in Chapter 2 of this manual. 

The kinds of control available include: 

• Authority to access a member for update (edit -lock) and, later, 
replace it by a promotion 

• Authority to promote a member from one controlled library to another 

• Authority to place an undefined member in a controlled library. (An 
undefined member is a member that does not currently exist in a 
controlled library and is not predefined.) 

• Ability to pack a member upon placing it in a controlled library 

• Ability to log the accessing and promoting of members 

• Authority to modify controls. 



Library Development 



The library hierarchy is developed by the library administrator. The 
library administrator has to determine the relation of the libraries to 
be controlled and the number of levels in the hierarchy. At least one 
group must be defined for each level. 

The group at the highest level of a hierarchy is called the Top Group 
(PROD in Figure 1). The group at the lowest level of a hierarchy is 
called the Bottom Group (DEPT1 and DEPT2 in Figure 1). You can have 
more than one group in each level of the hierarchy below the top group. 

A member can enter a controlled project only through a library in a 
bottom group. Thus, each controlled library in the bottom group of 
libraries is an Entry-Level Library , a library into which a member is 
promoted when entering the controlled project. 

All groups except the top group have a Target Group . A target group is 
a controlled group containing the library into which a member can be 
promoted. Specifying target groups is the means by which a library 
administrator defines the promotion hierarchy. 
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Referring again to Figure 1, we can categorize the different groups as 
follows: 

Top group PROD 

Bottom groups DEPT1 and DEPT2 

Target group for PROD none 

Target group for SYSTST PROD 

Target group for DEPT1 SYSTST 

Target group for DEPT2 SYSTST 

Group for which DEPT1 or DEPT2 is target none 

This points out that the top group is the only group that does not have 
a target group. Also, the bottom groups are the only groups that are 
not target groups. 

When defining the controls within the promotion hierarchy, the library 
administrator can identify those people who are authorized to: 

• Access a member with intent to update and promote it 

• Promote members to the entry- level library 

• Promote a member from one controlled library to another controlled 
library 

• Authorize additional library administrators. 

The naming of the people authorized to perform the various LMF functions 
is accomplished by entering their logon IDs into a named user set. A 
User Set is a collection of authorized user logon IDs. A user set is 
required whenever more than one person is to be authorized to perform 
particular functions. If only one person is authorized, that person's 
logon ID is specified. 

A user set is dynamic. Logon IDs can be added or deleted from the user 
set during the course of the project. However, only the library 
administrator can create the user set and add or delete entries in the 
user set. 

The library administrator can also create distribution tables. 
Distribution tables allow members common to several different library 
hierarchies of a project to be promoted into those hierarchies at the 
same time by a single promotion. A Distribution Table is a table 
containing the groups that identify the different library hierarchies 
into which a specified member is to be promoted. Members are 
distributed according to version numbers. A Version Number is used to 
associate a member with a particular promotion hierarchy. Version 
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numbers are assigned by the library administrator and set by the program 
developer. 



Library Use 



Tutorials 



To work with a controlled library, the user must have authorization to 
access a member for update. The user cannot edit, move, or copy a 
member into a controlled library. This is enforced through RACF or an 
equivalent protection system. Using a concatenated edit, the user must 
actually copy a member from a controlled library in order to work on it. 
Thus, members are updated in the user's private library. The updated 
member then goes through the promotion process to be returned to the 
controlled library. 

When a member is promoted to a controlled library, the user is asked for 
the "target" library. The user must specify the entry- level library. 
The "target" library for promotion of a member into a controlled library 
is an entry- level library. 

When a member is promoted from one controlled library to another 
controlled library, the user need not specify a target library. The 
library administrator defined all target libraries when the controlled 
project was developed. 



Tutorials are provided to help you in working with LMF. The tutorials 
aid both the library administrator and the user of controlled libraries 

Should you need assistance in your work, enter the command HELP on any 
panel. You will be provided with a tutorial for that panel. For 
example, you can use the tutorials to obtain definitions, information 
about messages, and general concepts as well as help on particular 
panels . 

Note: The panels shown in this manual are only representative of 
the panels in the product. While the contents are the same, the 
panels shown here may differ slightly in placement of fields and 
other elements. 
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CHAPTER 2. LIBRARY ADMINISTRATION 



Library administration involves: 

• Planning the library structure 

• Defining the library controls that create the structure 

• Maintaining the library and controls. 

The library administrator is responsible for performing these functions. 

In this chapter, we will examine the actions taken by the library 
administrator in planning the library structure, defining the library 
controls, and maintaining the library. We will use the library 
structure represented in Figure 1 to illustrate the actions of the 
library administrator. 

The library structure illustrated in Figure 1 represents a project, 
ISPFEXAM, having two sets of programmers. Each programmer has a set of 
private libraries (the M FR" and "MA M libraries) for development 
purposes. Members are moved into the controlled structure by being 
promoted to the entry- level controlled libraries from these private 
libraries. Promotion to the middle-level libraries can be for 
integrating and testing the work of the two groups (DEPT1 and DEPT2). 
Promotion to the top-level libraries can be for integrating and testing 
new material with older material, perhaps from a previous release. 

All library controls in each hierarchy can be created, together with the 
hierarchical controls, by using two panels, the Specify Library Controls 
panel and the Create or Update Library Controls panel. You create the 
library controls one at a time, starting with the top-level library and 
proceeding down the hierarchy to the bottom- level, or entry- level, 
library (or libraries). 

After all library controls have been created, you should allocate space 
for every library in your structure. This allocation is very important. 
Unless you allocate the space for your libraries, your structure will be 
unusable. 

Use the Data Set Utility, PDF option 3.2, to allocate space for data 
sets . 

To create the library hierarchy and define the library controls, it is 
necessary to plan the structure of the libraries. In other systems you 
may be accustomed to, there is one large library with status indicators 
identifying modules under development, in test, and so on. With LMF, 
members with the same status should be together in a single library 
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group. For example, stable programs may be in a top-level group of 
libraries and programs being tested may be in a different group of 
libraries in the hierarchy. 

Planning the library structure involves identifying the libraries to be 
managed and their relationship to each other in a promotion hierarchy. 

If there are many members with the same project name and type, you may 
improve system performance by breaking the one large project into two or 
three small projects. 

To create the library hierarchy and controls, take the following steps: 

1. Working down from the top group in the promotion hierarchy, identify 
each library in turn with its associated controls (option 8.1). 

2. Allocate and protect the data sets for each library. The data sets 
must be allocated as partitioned data sets (option 3.2). Do not 
password-protect these data sets. 

Note: When protecting the library, make sure that you give 
yourself RACF read-only authority. In addition, the user ID 
associated with the started task must have RACF update 
authority. For more information, see ISPF and ISPF/PDF for 
MVS Installation and Customization . 

3. Specify those users who are authorized to perform library functions 
(option 8.2). 

4. Activate the promotion hierarchy controls (option 8.4). 

Each of the four steps is discussed in this chapter. 

LMF will give you the results of your requested actions whether they are 
successful or unsuccessful. The message always appears on the right 
side of the top line of the panel. 
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INVOKING LMF UTILITIES 



Option 8 of the ISPF/PDF primary option menu, Figure 2, will take you 
into the library management utilities . 



OPTION ==> 8_ 

ISPF PARMS • 

1 BROWSE 

2 EDIT 

3 UTILITIES 

4 FOREGROUND ■ 

5 BATCH 

6 COMMAND 

7 DIALOG TEST ■ 

8 LM UTILITIES- 
C CHANGES 

T TUTORIAL 

X EXIT 



ISPF/PDF PRIMARY OPTION MENU 



Specify terminal and user parameters 

Display source data or output listings 

Create or change source data 

Perform utility functions 

Invoke language processors in foreground 

Submit job for language processing 

Enter TSO command or CLIST 

Perform dialog testing 

Perform library management utility functions 

Display summary of changes for this release 

Display information about ISPF/PDF 

Terminate ISPF using log and list defaults 



USERID 
TIME 

TERMINAL 
PF KEYS 



Z59FLG 
09:32 
3278T 
12 



Figure 2. ISPF/PDF Primary Option Menu 
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The first panel you will see is the Library Management Utilities panel, 
shown in Figure 3. 



OPTION ===> _ 

1 CONTROLS 

2 USER SET 

3 DISTRIBUTION 

4 ACTIVATE 

5 REVIEW 

T TUTORIAL 



LIBRARY MANAGEMENT UTILITIES 



Specify library attributes: 

Create, update, or delete promotion hierarchies, 
Authorize access to controls or members in hierarchies, 
Specify action taken when promoting members. 

Create, update, or delete list of users authorized 

to perform library functions. 

Create, update, or delete a distribution table to 

relate different promotion hierarchies. 

Activate or deactivate promotion hierarchy controls. 

Browse or print activity and library controls 

information. 

General information about the library management 

utility facility. 



Figure 3. Library Management Utilities Panel 



The options on the Library Management Utilities Panel are as follows: 



Controls 



User Set 



Distribution 



This option allows you to create your library 
hierarchies and to put the controls for the 
promotion hierarchies in place. This option 
is also used when you update or delete your 
promotion hierarchies, or create, update, 
or delete controls for members. 

This option allows you to specify those 
people who are authorized to perform the 
various library functions. You may define 
more than one user set. 

This option allows you to set up tables that 
permit the promotion of a member to different 
library hierarchies with just one promotion. 
Each library hierarchy can have only one 
distribution table. 
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4. Activate 



- This option allows you to activate or 
deactivate the controls you created. If 
you want to promote members into the 
hierarchy, or edit members from the 
hierarchy, you must activate the controls. 
If you want to update or delete any of the 
controls, you must first deactivate the 
controls . 



Review 



This option allows you to see how the 
library and member controls are set up, who 
accessed members for update, and who has 
promoted members. 



Tutorial 



This option allows you to obtain an overview 
of LMF. 



We will look at options 1 through 5 in greater detail in the following 
sections. Option T is discussed in "Tutorials" on page 8. 
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CONTROLS (OPTION 1) 



Selecting option 1, Controls, causes the Specify Library Controls panel 
to be displayed. A representation of this panel, with the information 
pertinent to the example described in Figure 1, is shown in Figure 4. 



SPECIFY LIBRARY CONTROLS 



OPTION ===> 1 



1 - Create or update controls for library hierarchies. 

2 - Delete library controls. 

3 - Create, update, or delete controls for members in a top library. 

ISPF LIBRARY: 

PROJECT ===> ISPFEXAM 

GROUP ===> SYSTST 

TYPE ===> PLI_ 
For option 3: 

MEMBER ===> (Name, truncated name, or * allowed) 



Figure 4. Specify Library Controls Panel 



This panel allows you to specify what you want to do with the controls. 
It requires that you identify the library controls you want to use. The 
option you select applies only for the library you identify. To create 
controls, always start with the top-level library, and then build your 
library hierarchy by going down one level at a time, until you create 
the controls for the entry- level library. You can create the controls 
for one library hierarchy at a time, or you can create all controls for 
all the libraries in a group before going to the next -lower group. 

The three options allow you to specify what you want done to the 
identified library: 

Option 1 - You want to create or update controls for the 
specified library. 
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Option 2 - You want to delete the controls for the specified 
library. 

Option 3 - You want to control who can access specific 
members in a library hierarchy. 

- If the members exist in the library, you can 
change the IDs of those who can access the 
members . 

- If the members do not exist in the library, 
you can predefine them. That is, you can 
control who can promote the specific member 
to a controlled library for the first time. 
Predefining members can be done only for 

a top-level group library. 
The member field should contain a name, a truncated 
name, or an asterisk. 
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Create Library Controls 



Selecting option 1 of the Specify Library Controls panel allows you to 
create the controls for the library specified. Remember that you have 
to create the controls in a top-down fashion; that is, the top-level 
library first, then successive lower-level libraries, until you create 
the controls for the entry- level library. 

Selecting option 1 results in the Create Or Update Library Controls 
panel. The panel for the middle- level PLI library in our example is 
shown in Figure 5 . 



CREATE OR UPDATE LIBRARY CONTROLS 



COMMAND ===> 



Enter the END command to save changes, or CANCEL to exit without saving. 



Global controls: 

TARGET GROUP FOR PROMOTE ===> PROD 
ADMINISTRATOR FOR ISPFEXAM => LIBADM 
LOG ACTIVITY => YES 



(Blank if SYSTST is top group) 
(YES or NO) 



Controls for library I SPFEXAM. SYSTST. PLI : 
AUTHORIZED PROMOTERS ===> USSET 
DISTRIBUTION TABLE NAME ===> 
COLLECTION NAME ===> 



(Blank if library is top) 

(Optional) 

(Optional) 



Controls for promotion into entry-level libraries: (Required only if entry-level) 
PACK DATA ON PROMOTION ===> NO (YES or NO) 
USER EXIT ON PROMOTION ===> (Optional) 

USER EXIT TYPE ===> (COMMAND or PROGRAM) 

UNDEFINED MEMBERS ALLOWED => YES (YES or NO) 

If Yes, enter the following controls for undefined members: 

MEMBER ACCESS CONTROL ===> PRIVATE (LIMITED, OPEN, or PRIVATE) 
AUTHORIZED ENTRY ID => (Blank for anyone) 

Figure 5. Create or Update Library Controls Panel 



This is a panel that allows you to define global controls, general 
library controls, entry- level library controls, and undefined member 
controls. We will start by seeing what the Global controls are and the 
information required for them. 
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Global Controls 



The following controls are global; that is, they apply to more than the 
library specified on the Specify Library Controls panel on page 14. 

Target Group for Promote - When a member is promoted within a 

controlled library, it is necessary to specify the group to 
which it is being promoted, the "target" group. The target 
group is always the next higher- level group. You leave this 
entry blank for a top-level group. The target group must have 
a library with controls defined. 

As PROD is the top-level group in the example shown in Figure 
1, members cannot be promoted out of PROD. Hence, there is no 
target group, so this entry is left blank. 

When the controls for a library in group SYSTST are created, 
the entry is 

TARGET GROUP FOR PROMOTE ===> PROD (Blank if SYSTST 

is top group) 

Similarly, the target group for libraries in both controlled 
groups DEPT1 and DEPT2 is SYSTST. 

The target group applies to all libraries with the defined 
project and group. 

Administrator for project - Enter the logon ID of the library 

administrator. A project may have more than one library 
administrator. If so, the name of a list is entered. That 
list, called a user set, contains the logon IDs of all library 
administrators who can update controls. User sets are created 
with the user set option (option 8.2). The user set must 
exist before it can be used as a library administrator. If 
library administrator is a user set and your logon ID is on 
the list, you cannot remove yourself from that list. Some 
other person on the list can remove your ID, if necessary. 

For our example, we have a single library administrator with 
the logon LIBADM. The administrator is global with respect to 
the controlled project. 

Log Activity - If you want all library activity logged, enter YES; 

otherwise, enter NO. Log activity applies only to the library 
hierarchy; that is, those libraries with the given project and 
type that have the same top group. 

Note: If you specify that the activities are to be logged, you 
must allocate space for a log data set for each type whose 
activity is to be tracked. To allocate the data set, use the Data 
Set Utility, PDF option 3.2. Use the name 

pro j ect . type . ACTLOG 
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for the data set. To allocate space for the activity log for type 
PLI of our example, you specify the name ISPFEXAM.PLI .ACTLOG. The 
data set allocated must be sequential and have a record length of 
90. The block size, if blocking is desired, can be defined to be 
whatever is most efficient for your installation. 

Log activity is global since it records the activity for each 
library in the library hierarchy. 



General Library Controls 



The items discussed in this section apply to the library specified on 
the Specify Library Controls panel on page 14. For our example, note 
that we displayed: 

Controls for library ISPFEXAM.SYSTST.PLI 

on the Create or Update Library Controls panel on page 16. 

The general library controls on the panel are: 

Authorized Promoters - This item specifies the person, or persons, 

authorized to promote a member from the specified library to 
the library in the target group. It is either the logon ID of 
the person or the name of a user set that contains the logon 
IDs of the people so authorized. 

If the library is contained in a top group, you must leave 
this item blank. If the library is not contained in a top 
group, Authorized Promoters must be entered, and the target 
group must be specified. 

Distribution Table Name - If you want to promote a member into more 

than one hierarchy, specify the hierarchies in a distribution 
table. The name of the table for this hierarchy is specified 
here. Distribution tables are discussed in "Distribution" on 
page 30. 

Collection Name - If you want to label a particular set of promotions in 
the activity log, enter a name. The collection name is a user 
field included in the activity log for each promotion. It 
could be used to group promotions by driver or release. 



Entry-Level Library Controls 



The following items refer to promoting a member to a controlled library. 
A member can be promoted to a controlled hierarchy only by promoting it 
into an entry- level library. Therefore, these controls are for an 
entry-level library, as illustrated by the Create or Update Library 
Controls panel in Figure 6. 
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- CREATE OR UPDATE LIBRARY CONTROLS 

COMMAND ===> 

Enter the END command to save changes, or CANCEL to exit without saving. 

Global controls : 

TARGET GROUP FOR PROMOTE ===> SYSTST (Blank if DEPT1 is top group) 

ADMINISTRATOR FOR ISPFEXAM ===> LIBADM 

LOG ACTIVITY ===> YES (YES or NO) 

Controls for library ISPFEXAM.DEPT1 .LOAD 

AUTHORIZED PROMOTERS ===> USSET (Blank if library is top) 

DISTRIBUTION TABLE NAME ===> (Optional) 

COLLECTION NAME ===> (Optional) 

Controls for promotion into entry level libraries: (Req. only if entry level) 
PACK DATA ON PROMOTION => NO (YES or NO) 

USER EXIT ON PROMOTION ===> PROMCHEK (Optional) 
USER EXIT TYPE ===> COMMAND (COMMAND or PROGRAM) 

UNDEFINED MEMBERS ALLOWED ===> YES (YES or NO) 

If YES, enter the following controls for undefined members: 

MEMBER ACCESS CONTROL ===> PRIVATE (LIMITED, OPEN, OR PRIVATE) 

AUTHORIZED ENTRY ID ===> (Blank for anyone) 



Figure 6. Create or Update Library Controls Panel 



Pack Data - This refers to members being promoted to the library. If 
you want the data packed to save space when it is promoted 
into the entry- level library, specify YES here. NO is 
specified when the panel is presented. 

The program developer can override the Pack Data field 
specification when the member is promoted. After the member 
is promoted, the data will remain packed or unpacked 
throughout the hierarchy. 

PACK uses a unique ISPF data compression routine. Attempts to 
access or execute the data outside of PDF can cause 
unpredictable results. See the description of the Edit PACK 
command in ISPF/PDF for MVS Program Reference for more 
information. 

User Exit Name - If you decide to do additional operations, such as 

validation, compression, compilation as examples, on a member 
being promoted into the library, this name specifies the exit 
for the desired function. See Appendix A for more 
information. The user exit name for the example in Appendix A 
is PROMCHEK. 
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User Exit Type - Indicates whether the user exit is a command or a 

program. For the example in Appendix A, the user exit type is 
COMMAND. 

Undefined Members - An undefined member is a member that does not 

exist in a controlled library or does not have member controls 
predefined. Enter YES or NO. YES means that an undefined 
member can be promoted to a controlled library. If you enter 
YES, and if the members are not predefined, then member 
controls are created for them according to the information in 
the next two fields . NO means that members that have no 
controls associated with them cannot be promoted to the 
hierarchy. For this situation, "new" members can be promoted 
into the hierarchy only if they are predefined. The next two 
fields are ignored if the entry is NO. 

Access Control - Specifies the ownership (Access ID) of the member when 
controls are created for it. Access to an undefined member 
may be: 

Open Anyone can access and update the member. 

Limited The access of the member for update depends on the 
Authorized Entry ID. If the Authorized Entry ID is: 

blank anyone can access the member for 

update (the same as having the 
access control of open) . 

logon ID only that person can access the 
member for update (the same as 
having the access control as 
private) . 

user set name anyone in the user set can access 
the member for update. 

Private Only the person who promoted the member can access 
and update the member. 

Authorized Entry ID - This item specifies the person(s) authorized to 
promote an undefined member to the controlled library. It is 
either the logon ID of the person or the name of a user set 
that contains the logon IDs of the people so authorized. If 
this field is left blank, anyone can promote undefined 
members . 

After all necessary fields are correctly specified on the Create or 
Update Library Controls panel, enter the END command. The result will 
be a display of the Specify Library Controls panel as shown on page 14 
with the top line stating that the controls have been created. That top 
line looks like: 



SPECIFY LIBRARY CONTROLS CONTROLS CREATED 
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To update library controls, you again select option 1 in the Specify 
Library Controls panel, shown on page 14. However, you will not be 
given the entire Create or Update Library Controls panel if lower-level 
libraries have been specified. If you specify an entry-level library, 
you get the entire panel. To update all but the lowest- level libraries, 
a panel, Figure 7, is displayed. 



CREATE OR UPDATE LIBRARY CONTROLS 



COMMAND => 

Enter the END command to save changes, or CANCEL to exit without saving. 

Global controls: 

TARGET GROUP FOR PROMOTE ===> (Blank if PROD is top group) 

ADMINISTRATOR FOR ISPFEXAM ==> LIB ADM 

LOG ACTIVITY ===> YES (YES or NO) 

Controls for library ISPFEXAM. PROD. PL I 

AUTHORIZED PROMOTERS ===> (Blank if library is top) 

DISTRIBUTION TABLE NAME ===> (Optional) 

COLLECTION NAME ===> RELEASEl (Optional) 



Figure 7. Create or Update Library Controls Panel 



The panel above has a Collection Name of RELEASEl specified. The use of 
the Collection Name is illustrated in the activity log on page 41. 



Delete Library Controls 



The only way to delete the library controls that have been saved is by 
selecting option 2 of the Specify Library Controls panel. The primary 
command CANCEL will not delete library controls that have been saved. 

When you select option 2, the CONFIRM DELETE panel (Figure 8) is 
displayed. 
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--_.-,--.------.- CONFIRM DELETE 

COMMAND •==> _ 

CONTROLS FOR LIBRARY: ISPFEXAM.PROD.PLI 



INSTRUCTIONS : 

Press ENTER key to confirm delete request. 
Enter END command to cancel delete request 



Figure 8. Confirm Delete Panel 



After pressing the ENTER key to confirm the delete request, a message on 
the Specify Library Controls panel will indicate whether the deletion 
was successful or unsuccessful. 

There are three things you must be careful about when you delete library 
controls. First, the library controls must be deactivated; second, the 
library must be empty (that is, contain no member controls); and third, 
after deletion the library structure must retain validity. Only those 
members in the library whose controls are being deleted should be 
removed. You should delete library controls before deleting the 
physical data sets. 

Note: Once the hierarchy is deactivated, you can normally delete 
all but one of the libraries in a group of the promotion 
hierarchy. That one remaining library can also be deleted 
provided it is not the target library for any other library in the 
controlled project. 

The procedure for deleting library controls is: 
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1. Deactivate the hierarchy (top group) that contains the controls. 
The section "Activate" on page 37 explains how controls are 
deactivated. 

2. If you are deleting a top group, you must remove all predefined 
members and members that are available for update. The section on 
"Member Controls" explains how these entries can be deleted. 

3. Remove a promoted member that is to be retained by promoting it to 
the next level in the library hierarchy. The section "Promotion 
Within the Controlled Library" on page 64 explains how to promote a 
member to the next level of a library hierarchy. 

4. Remove a promoted member that is not to be retained by giving it a 
zero length. This is accomplished by: 

a. Accessing the member for update (see "Accessing a Library 
Member" on page 54) . 

b. Deleting all records from the member. 

c. Promoting the zero length member to the top -group (see 
"Promotion to the Controlled Library" on page 61 and "Promotion 
Within the Controlled Library" on page 64) . 

5. Retain the validity of the hierarchy by changing the target group 
for lower- level libraries to the next higher- level group. For 
example, suppose that library ISPFEXAM.SYSTST.PLI is being deleted. 
The target group for the libraries ISPFEXAM.DEPT1.PLI and 
ISPFEXAM.DEPT2.PLI must be changed from SYSTST to PROD. Target 
groups are changed using the Create Or Update Library Controls panel 
(see page 21) . 

6. Delete the library controls. 

If you are deleting the controls for more than one library in the 
library hierarchy, start with the lowest- level library and work up to 
the highest- level library whose controls are to be deleted. 

After you have deleted the library controls, make sure you activate the 
remaining library controls, if any. 



Member Controls 



Option 3 of the Specify Library Controls panel is used to control who 
can access members in a library hierarchy. If the member exists in the 
library, IDs of those who can access it can be changed if the member is 
not edit-locked or does not exist at a lower level. If the member does 
not exist, it can be predefined. The Specify Library Controls panel 
that would appear for our example is shown in Figure 9. 
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- SPECIFY LIBRARY CONTROLS 

OPTION => 3 

1 - Create or update controls for library hierarchies. 

2 - Delete library controls. 

3 - Create, update, or delete controls for members in a top library. 

ISPF LIBRARY: 

PROJECT ==> ISPFEXAM 

GROUP => PROD 

TYPE => MSGS 
For option 3: 

MEMBER => * (Name, truncated name, or * allowed) 



Figure 9. Specify Library Controls Panel 



Notice that the top-group library is specified. Specifying member 
controls for the top-group library specifies them for the whole library 
hierarchy. If a member exists in a controlled library, or if controls 
have been created for the member, then you can change which users are 
allowed to access the member if the member exists only at the top level. 
The access ID cannot be changed for members that are edit -locked or 
exist at lower levels. You can also predefine controls for members. 
Predefining controls for members allows you to specify who can access a 
particular member, before that member is promoted to the controlled 
library. 

For this option, the MEMBER must be specified as a member name, a 
truncated name, or an asterisk. The MEMBER designation determines which 
member controls are displayed and, hence, updated or deleted. 

Member name Only the controls for the member with that name are 
displayed. 

Truncated name A truncated name ends with * to differentiate it from a 
member name. The controls for all members whose names 
start with the truncated name will be displayed. 
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* All member controls will be displayed. 

To demonstrate the difference in designating the member name as a 
truncated name or *, assume that the library ISPFEXAM.PROD.MSGS has 
members CMSG1, EMSG1, EMSG2, SMSG1, SMSG2... Designating the member 
name as 

MEMBER ==> * 

will display the controls for each member of the library. However, 
using a truncated name, such as 



MEMBER 



==> EM* 



will cause the display of controls for all members whose names begin 
with EM; namely, the controls for EMSG1 and EMSG2. 

Selecting option 3 of the Specify Library Controls panel will produce 
the Specify Member Level Controls panel, as shown in Figure 10. 



SPECIFY MEMBER LEVEL CONTROLS 



COMMAND ==> 



• ROW 1 OF 13 

SCROLL ==> PAGE 



Add, delete, or change member names or access ids for 

library: ISPFEXAM.PROD.MSGS 

Enter the END command to save changes, or CANCEL to exit without saving, 



MEMBER 


ACCESS 


DELETE 


NAME 


ID 


STATUS 


1111 CMSG1 


FR1 




' * " EMSG1 


FR2 


T 


1 ' ' ' EMSG2 


MAI 


P 


' ' " SMSG1 


FR3 


P 


' ' * ' SMSG2 


MA2 


P 



(P=Predefined, T=Top Group, 
blank=Not de let able and cannot 
alter access id) 



Figure 10. Specify Member Level Controls Panel 



This panel shows individual member controls of the library with the 
corresponding access IDs . The access IDs are either logon IDs or user 
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set names of those people who have the authority to access the 
corresponding members. The access ID for a predefined member determines 
who can promote it to the hierarchy. 

The column labeled Delete Status specifies whether the member controls 
can be deleted. Delete Status is not an input field. The controls for 
any member with a blank Delete Status (CMSG1 in our example) cannot be 
deleted and the access ID cannot be altered in its present state. There 
are two ways to delete the controls. First, the member can be promoted 
to a top group and then deleted; second, the member can be edited into 
your private library, made into a zero- length member, then promoted 
through the hierarchy to the top level. The way to make a member a 
zero-length member is to delete all the lines of the member. The access 
ID cannot be changed for a member with a blank Delete Status. Access ID 
is an input field, but an error message will result if you try to save a 
changed access ID. Once the member is promoted to the top group, you 
cannot alter the access ID. 

If a member has a P in the Delete Status column (EMSG2, SMSG1, and SMSG2 
in our example), it is a predefined member. If there is a T in the 
Delete Status column (EMSG1 in our example), the member is in a top 
group. Any member with a P or T Delete Status can be deleted by the 
delete line command. However, if the status is T, the physical member 
is not deleted. 

The apostrophes on the left define the line command area where you can 
enter commands such as insert (I), delete (D) , and repeat (R) . Only the 
controls for predefined members and members available for update in the 
top group can be deleted. The line commands are useful when you update 
this list. 

The primary commands available are CANCEL, LOCATE, and END. LOCATE can 
be used to locate either a member name or an access ID. 

As soon as a member is promoted into an entry- level library, controls 
are created for that member. Thus, controls for an undefined member are 
created in accordance with the Create Controls panel (page 19) and 
controls for a predefined member are created in accordance with the 
Member Control panel (page 25). The controls for a member are created 
after a promotion to a controlled library has begun. 

USER SET (OPTION 2) 

A user set is used in four circumstances : 

• When there is more than one person assigned the authority to promote 
members out of a controlled library 

• With the promotion hierarchy when more than one promoter is needed 

• To identify those people authorized to promote undefined members to 
the controlled library 
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• As an access ID for a member when there is more than one person 
authorized to access that member. 

The user set lists the logon IDs for those people who are authorized to 
promote members, or to have access to particular library members or 
library controls. The same user set need not apply to all four cases 
noted above. For our example, only one user set, named USSET, is 
defined. 

Option 2 of the Library Management Utilities panel (see page 12) is used 
to get to the user set specification. The result of choosing option 2 
is the Specify User Sets panel, shown in Figure 11. 



SPECIFY USER SETS 



OPTION => 1 



1 - Create or update user set 

2 - Delete user set 

PROJECT — > ISPFEXAM 
USER SET NAME ===> USSET 



Figure 11. Specify User Sets Panel 



The Specify User Sets panel is used for each user set you want to 
specify. The project name and user set name must be specified for 
either option you select. 

Option 1 allows you to create, or update, a user set. For 
our example, we select option 1 to create the 
user set named USSET. 

Option 2 allows you to delete a user set. 
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Note: If you want to specify a user set as the library 
administrator under global controls on the Create and Update 
Library Controls panel (see page 21), you must define the user set 
before you use the name in creating library controls. Your logon 
ID must be in the user set. Failure to define the user set first 
in this situation will prevent the controls from being created. 

When you select option 1, the Create or Update User Sets panel, shown in 
Figure 12, is displayed. 



CREATE OR UPDATE USER SETS 

COMMAND ===> SCROLL ==> HALF 

Add, delete, or change user logon ids for user set: USSET 

Enter the END command to save changes, or CANCEL to exit without saving. 

LOGON ID DESCRIPTION 

FR1 FRANK 

FR2 JOE 

FR3 ALAN 
LIB ADM 



MAI PETE 

MA2 RUPERT 



Figure 12. Create or Update User Sets Panel 



The apostrophes on the left define the line command area where you can 
enter commands such as insert (I), delete (D), and repeat (R) . The line 
commands are useful when you update this list. 

The primary commands available are CANCEL, LOCATE, and END. You can 
perform a LOCATE only on the logon ID. 

The column labeled "Description" allows you to enter information 
pertaining to the logon IDs, if desired. The data in this column is 
neither checked nor used by LMF. In our example, the name of the person 
associated with each logon ID is indicated in the Description column. 
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User sets can be updated while the controls are active. 

You cannot delete your own logon ID from a library administrator user 
set. If you want your logon ID deleted from such a user set, you must 
have someone else who is specified as a library administrator do it for 
you. This ensures that there is always a valid administrator. 

Selecting option 2, Delete User Set, will cause a Confirm Delete panel, 
shown in Figure 13, to be displayed. 



COMMAND => _ 

PROJECT: ISPFEXAM 
USER SET NAME: USSET 



CONFIRM DELETE 



INSTRUCTIONS: 

Press ENTER key to confirm delete request. 
Enter END command to cancel delete request 



Figure 13. Confirm Delete Panel 



If you want to delete a user set that is used as a library 
administrator, you must first change the administrator control (Create 
or Update Library Controls, option 8.1.1) to a different valid library 
administrator. Once the user set is no longer used as a library 
administrator, it can be deleted. 

Note: Although the user set you specify when selecting option 2 
is deleted, library controls referencing that user set are not 
deleted. You must, therefore, update all library controls that 
refer to the deleted user set. 
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DISTRIBUTION (OPTION 3) 



The Distribution option, option 3 on the Library Management Utilities 
panel, is used to specify a distribution table. 

A distribution table allows you to promote a member from a private 
library into multiple entry-level libraries with a single interaction. 
It also allows you to promote members from one level of a library 
hierarchy to another. Let's look at an example. 

Assume that you have a project, PROJ, with two separate library 
hierarchies, as illustrated in Figure 2. For simplicity, only one type 
and two hierarchies are included in this example. 

There are various reasons for having separate library hierarchies in a 
project, including: 

• Parallel efforts with different implementation techniques are in 
progress, with some members in common. 

• One hierarchy is used as a checkpoint set for the other hierarchy. 

• One hierarchy is used for updating purposes while the other 
hierarchy, not accessible for updating, maintains the latest updated 
state. 
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PROJ 



TOPI 



TOP2 



1 p 1 




1 P 1 


1 L | 


TOP-LEVEL 


1 L | 


1 I 1 




1 I 1 



MIDI 



MID2 



MIDDLE -LEVEL 



BOT1 



BOT2 



ENTRY -LEVEL 



PRIV 



Figure 14. Sample Structure for Distributive Promotion 
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There are other reasons that your installation may have for having 
separate library hierarchies within a project. 

Now, suppose a member, MEMB, has been created or updated in a private 
library. MEMB is to be promoted to both entry- level libraries depicted 
in Figure 14, and only one promotion is to be used. Such a distributive 
promotion can be accomplished with a distribution table. The 
distribution table contains version numbers of members to be 
distributively promoted, together with the target groups for each member 
identified. 

Version numbers are established by the library administrator when the 
distribution table is created. These version numbers must be given to 
the developers who assign them to the members they are developing. 
Version numbers are assigned using the edit VERSION primary command or 
by using the Reset Utility, PDF option 3.5. For a discussion of version 
numbers, refer to ISPF/PDF for MVS Program Reference . 

The library hierarchies that are associated with a distribution table 
must be identified as such. This association is accomplished by 
entering the name of the distribution table in the Create and Update 
Library Controls panel of each of the target libraries of the 
hierarchies. For the structure shown in Figure 14, the target libraries 
are the entry- level libraries. Thus, if the distribution table is named 
DIST, the entry in each of the Create and Update Library Controls panels 
for the libraries PR0J.B0T1 .PLI and PR0J.B0T2.PLI is 

DISTRIBUTION TABLE NAME ===> DIST 

Only one library in the library hierarchy may have the name of the 
distribution table. However, there may be another distribution table in 
the promotion hierarchy associated with another library type. 

Distributive promotion is not confined to promotion into entry- level 
libraries. You can, if you wish, promote a member from an entry-level 
library into two middle-level libraries, from an entry-level library 
into a middle- level library and a top-level library, or from a 
middle-level library into two top-level libraries. In each case, the 
name of the distribution table is associated with the target libraries. 

Note: When a distribution table is associated with a library 
hierarchy, all members promoted to, or within, that hierarchy must 
have a version number listed in the distribution table. If that 
member is not to be promoted to a library hierarchy other than its 
own hierarchy, its version number must still appear in the 
distribution table. Version numbers of members that are promoted 
in more than one hierarchy appear several times in the 
distribution table, once for each hierarchy. 

To define a distribution table, select option 3 of the Library 
Management Utilities. The panel shown in Figure 15 is displayed. 
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- - SPECIFY DISTRIBUTION TABLES 

OPTION ===> 1 

1 - Create or update distribution table 

2 - Delete distribution table 

PROJECT ===> PROJ 

DISTRIBUTION TABLE NAME ===> DIST 



Figure 15. Specify Distribution Tables Panel 



There are two options. You can elect to create or update a distribution 
table or to delete a distribution table. In either case, you must 
specify the project name and the name of the distribution table. 

If you select option 1, the panel shown in Figure 16 is displayed. 
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CREATE OR UPDATE DISTRIBUTION TABLES ROW 1 OF 13 

COMMAND => SCROLL ==> HALF 

Add, delete, or change version numbers and target groups for distribution 

table: DIST 
Enter the END command to save changes, or CANCEL to exit without saving. 





VERSION 


TARGET 




NUMBER 


GROUP 


lilt 


11 


B0T1 


till 


11 


B0T2 


lilt 


12 


B0T1 


till 


13 


B0T2 



Figure 16. Create or Update Distribution Tables Panel 



In the panel shown above, the member whose version number is 11 is 
promoted into the two entry-level libraries, B0T1 and B0T2. The members 
with version numbers 12 and 13 are each promoted into only one 
entry-level library, B0T1 and B0T2, respectively. 

The apostrophes on the left define the line command area where you can 
enter commands such as insert (I), delete (D) , and repeat (R) . The line 
commands are useful when you update this list. 

The primary commands available are CANCEL, LOCATE, and END. You can use 
the LOCATE command with either version number or target group. 

If you select option 2 of the Specify Distribution Tables panel to 
delete a distribution table, the Confirm Delete panel, as shown in 
Figure 17, is displayed. 
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--- CONFIRM DELETE • 

COMMAND => _ 

PROJECT: PRO J 

DISTRIBUTION TABLE NAME: DIST 

INSTRUCTIONS : 

Press ENTER key to confirm delete request. 
Enter END command to cancel delete request 



Figure 17. Confirm Delete Panel 



If you confirm the deletion, the distribution table will be deleted. 
However, library controls that refer to that distribution table are not 
deleted. You have to update the library controls that refer to the 
deleted distribution table. 

When you create, update, or delete a distribution table, various checks 
are made to ensure that the distribution table can be created, updated, 
or deleted. The checks made are: 

• Creation of a Distribution Table 

- To Create a Distribution Table: 

— The user must be an authorized project administrator. 

— The specified project must exist. 

— The specified project must not be in use by any other 
project administrator. 

- To Save a Created Distribution Table: 
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— For each group entered in the distribution table, controls 
must be defined for at least one library in that group. 

— For each group entered in the distribution table, all 
libraries within that promotion hierarchy must be 
deactivated. 

— For each group entered in the distribution table, all 
members belonging to any library using that group qualifier 
and the specified distribution table must be in the top 
group and available. 

— The members of the library hierarchy must be available for 
update up to and including the level at which the 
distribution table is specified. 

— For each library hierarchy associated with a group in a 
distribution table, only one library can have a distribution 
table specified. (Groups TOP and MIDDLE for the same 
hierarchy cannot both be in a distribution table.) 

Updating a Distribution Table 

— To Access a Distribution Table for Update: 

— The user must be an authorized project administrator. 

— The specified project must exist. 

— The specified project must not be in use by any other 
project administrator. 

— For each group entered in the distribution table, all 
libraries using that hierarchy must be deactivated. 

— The members of the library hierarchy must be available for 
update up to and including the level at which the 
distribution table is specified. 

- To Save an Updated Distribution Table: 

— For each group entered in the distribution table, controls 
must be defined for at least one library in that group. 

— For each group entered in the distribution table, all 
libraries within that promotion hierarchy must be 
deactivated. 

— For each group entered in the distribution table, all 
members belonging to any library using the group qualifier 
and the specified distribution table must be in the top 
group and available. 
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— The members of the library hierarchy must be available for 
update up to and including the level at which the 
distribution table is specified. 

— For each library hierarchy associated with a group in a 
distribution table only one library can have a distribution 
table specified. (Groups TOP and MIDDLE from the same 
hierarchy cannot both be in a distribution table.) 

Note: There does not have to be a library in the 
hierarchy for each group in the distribution table. 
This allows the user to delete groups out of the 
hierarchy before deleting them from the distribution 
table. Libraries must exist for all groups only when 
saving the distribution table. 

• Deleting a Distribution Table 

To Access a Distribution Table for Deletion: 

— The user must be an authorized project administrator. 

— The specified project must exist. 

— The specified project must not be in use by any other project 
administrator . 

— The specified distribution table must exist. 

— For each group entered in the distribution table, all libraries . 
using that group qualifier must be deactivated. 

Note: For each group in the distribution table, there does not 
have to be a library in the hierarchy using that group. Thus, the 
user may delete the entire distribution table after some or all of 
the groups from the hierarchy have been deleted. 

If any of the above checks fail, you will be notified by a message. The 
manner of continuing depends upon the check that has failed. Therefore, 
if you get a message, request the tutorial for that failed check to 
determine how to proceed. 



ACTIVATE (OPTION 4) 



For the example, you created the library structure, put the controls in 
place, defined the user set, and created and protected the data sets. 
In order to allow the library structure to be used, the controls must be 
activated. Option 4 on the Library Management Utilities panel allows 
you to activate the controls. When you select option 4, the panel shown 
in Figure 18 is displayed. 
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— ACTIVATE OR DEACTIVATE CONTROLS 

OPTION ===> 1 

1 - Activate controls and display hierarchy structure 

2 - Deactivate controls 

PROJECT ===> ISPFEXAM 

TOP GROUP => PROD_ (* for all top groups) 



Figure 18. Activate or Deactivate Controls Panel 



The top-group name is required to activate or deactivate the controls 
for a promotion hierarchy. If you choose option 1, activate controls, 
and the activation is successful, a panel showing your structure is 
displayed. For our example, the panel is that shown in Figure 19. 
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HIERARCHY (IES) ACTIVATED - ISPFEXAM.PROD LINE OOOOOO COL 001 080 

COMMAND ==> _ SCROLL => CSR 

********************************** TOP OF DATA ******************************** 



STRUCTURE FOR - ISPFEXAM DATE: 83/06/30 TIME: 09:56 



1 PROD Where: 

2 SYSTST 1, 2 ... 50 Indicates hierarchical position 
B DEPT1 B Indicates bottom group 

B DEPT2 



DEFINED TYPES 
LOAD 
MSGS 
PLI 



********************************* g OTTOM OF DATA ****************************** 
Figure 19 . Library Structure Panel 



Before you update library controls, you must deactivate the library 
controls. To do this, use option 2 on the Activate or Deactivate 
Controls panel. Only the person who deactivates the controls can 
activate them again. 

When a library is active, the only controls you can update are user sets 
and member controls. You can also review the activity log or the 
controls when the library is active. 

REVIEW (OPTION 5) 

Selecting option 5 on the Library Management Utilities panel allows you 
to look at the log activity and the library controls. Anyone can select 
this option. 

Selecting option 5 results in the display shown in Figure 20. 
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OPTION ==> _ 

1 ACTIVITY LOG 

2 CONTROL STATUS 

3 MEMBER STATUS 



REVIEW ACTIVITY AND CONTROLS • 

Update and promote activity 
Library control data 
Member control data 



Figure 20. Review Activity and Controls Panel 



Option 1 allows you to look at the activity log. This log lists the 
promotion activities and update activities that have taken place. 

Option 2 allows you to look at the library control data. 

Option 3 allows you to look at the member control data to determine 
those members that were predefined and those that have been promoted 
into the controlled library. 

Each of these options is discussed below. 



Activity Log 



When you select option 1, the Activity Log Review panel (Figure 21) is 
displayed. 
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ACTIVITY LOG REVIEW 

OPTION ==> 2 

1 - Browse activity log 

2 - Print activity log 



ISPF LIBRARY: 

PROJECT ==> ISPFEXAM 

TOP GROUP => PROD (* for all top groups) 

TYPE ===> PLI (* for all types) 

MEMBER ==> * (Name, truncated name, or * allowed) 



Figure 21. Activity Log Review Panel 



You specify the member whose log activity you want to review. If you 
specify an asterisk (*) for top group, type, and member, you can review 
the activities logged for every member in all controlled libraries. 

Option 1 causes the log for the specified members to be displayed. This 
display is scrollable. 

Option 2 causes the log activity data to be sent to the ISPF list data 
set. You can then obtain a hardcopy printout of the log activity data. 

An example of a printout of an activity log for project ISPFEXAM is 
shown in Figure 22. 
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ACTIVITY LOG OF PROJECT : ISPFEXAM GROUP : PROD 



PAGE 1 



TYPE : 


PLI 














MEMBER 


GROUP 


ACTION 


USER ID 


DATE 


TIME 


VER 


MOD COLLECT REASON 


AAA 


SYSTST 


EDITLOCK 


FR2 


83/11/21 


11:05 


01 


00 


AAA 


SYSTST 


FREE 


FR2 


83/11/21 


11:06 


01 


00 


AAA 


SYSTST 


EDITLOCK 


FR2 


83/11/29 


16:54 


01 


00 


AAA 


DEPT2 


MOVE 


FR2 


83/11/29 


17:03 


01 


01 PROBLEM REPORT 17 


AAA 


SYSTST 


MOVE 


FR2 


83/11/29 


17:27 


01 


01 


AAA 


PROD 


MOVE 


FR2 


83/11/29 


17:28 


01 


01 RELEASE 1 


BBB 


PROD 


EDITLOCK 


MA2 


83/11/29 


16:56 


01 


00 


BBB 


DEPT2 


MOVE 


MA2 


83/11/29 


17:26 


01 


01 


BBB 


SYSTST 


MOVE 


MA2 


83/11/29 


17:27 


01 


01 


CCC 


DEPT1 


EDITLOCK 


MAI 


83/11/22 


17:10 


01 : 


> 00 PROBLEM REPORT 43 


CCC 


DEPT1 


FREE 


MAI 


83/11/22 


17:11 


01 


00 


DDD 


SYSTST 


EDITLOCK 


FR3 


83/11/21 


14:41 


01 


00 


DDD 


DEPT2 


MOVE 


FR3 


83/11/21 


14:48 


01 


01 


DDD 


DEPT2 


EDITLOCK 


FR3 


83/11/22 


09:35 


01 


01 


Figure 


22. Sample Activity Log 


Listing 









Note: The date information is displayed in the national format 
of the language being used. 

The headings are: 

MEMBER Member name 



GROUP 



Group in which the action was done 

ACTION The activity performed on the member 

move the member was promoted to an entry- level 
library 

free the member was made available for update 

editlock the member was locked for update purposes. The 
member can be promoted or freed only by the 
person who accessed it. The person whose logon 
ID is listed is the only one who is allowed to 
change the member in the controlled library, 
which must be done by promoting the member from 
an uncontrolled library. 
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A discussion of these actions is given in the promotion of 
members on page 63. 

USER ID User who requested the action 

DATE Date, in national language format, when the action occurred 

TIME Time, in hh:mm 24 -hour format, when the action occurred 

VER Version number 

MOD Modification level 

COLLECT Collection name, as specified on the Controls panel 

REASON Reason code as specified on the Promotion panel 

If you want to use the data in the activity log to produce special 
reports, you must know the record layout. The record layout for the 
activity log, project. type. ACTLOG, is specified in Appendix B. 



Control Status 



When you select option 2 on the Review Activity and Controls panel, the 
Control Status Review panel (Figure 23) is displayed. 
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CONTROL STATUS REVIEW 



OPTION 



=> 2 



1 - Browse control status 

2 - Print control status 

3 - Write control status to a data set 

ISPF LIBRARY: 



PROJECT 
TOP GROUP 
TYPE 
MEMBER 



==> ISPFEXAM 
=> PROD 



OUTPUT DATA SET 

DATA SET NAME ===> 



(* for all top groups) 

(* for all types) 

(Name, truncated name, or 

(Option 3 only) 



allowed) 



Figure 23. Control Status Review Panel 



You specify the member whose library control status you want to review. 
If you specify an asterisk (*) for top group, type, and member, you can 
review the library control status for every member in all top-level 
groups of the controlled library. 

Option 1 causes the library control status for the specified members to 
be displayed. This display is scrollable. 

Option 2 causes the library control data to be sent to the ISPF list 
data set. You can then obtain a hardcopy printout of the library 
control data. 

Option 3 causes the library control data to be written to a data set 
that you specify. You specify the data set name where indicated on the 
panel. The data set will be allocated if it does not already exist. 
You can then do what you want with the library control data, such as 
formatting it in different ways for different reports. See Appendix B 
for record formats . 

An example of a printout of a control status listing for project 
ISPFEXAM is shown in Figure 24. 
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LIBRARY CONTROL STATUS REVIEW PAGE 1 

PROJECT: I SPFEXAM ADMINISTRATOR: LIB ADM UPDATE IN PROGRESS:NO DATE:83/11/21 TIME:14:51 

GROUP: PROD TARGET: TOP GROUP LEVEL: TOP 

LOG ACCESS ID PROMOTION PROMOTION COLLECT 

TYPE PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 

LOAD 
MSGS 





NO 


NO 












NO 


NO 










MEMBER 


VER 


MOD 


GROUP 


ACCESS 


ID 


STATUS 


EMSG1 


01 


00 


PROD 


FR1 




AVAILABLE 


EMSG2 






PROD 


MAI 




PREDEFINED 


SMSG1 






PROD 


FR3 




PREDEFINED 


SMSG2 






PROD 


MA2 




PREDEFINED 



TYPE 



PLI 



LOG ACCESS ID PROMOTION PROMOTION COLLECT 

PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 



NO YES 
MEMBER VER MOD GROUP 
BBB 01 00 PROD 



ACCESS ID STATUS 
MA2 AVAILABLE 



GROUP: SYSTST 



TARGET: PROD 



LEVEL: 2 



LOG ACCESS ID PROMOTION PROMOTION COLLECT 

TYPE PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 



FR1 


NO NO 




FR1 


NO NO 




MEMBER 


VER MOD 


GROUP 


CMSG1 


01 00 


SYSTST 



ACCESS ID STATUS 
FR2 AVAILABLE 



LOG ACCESS ID PROMOTION PROMOTION COLLECT 

TYPE PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 



PLI USSET 



NO YES 
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GROUP: DEPT1 TARGET: SYSTST LEVEL: BOTTOM 

LOG ACCESS ID PROMOTION PROMOTION COLLECT 

TYPE PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 



LOAD LIBADM NO NO NO UNDEFINED MEMBERS PROMCHEK 

MSGS FR1 NO NO NO UNDEFINED MEMBERS 

PLI USSET NO YES PRIVATE 

MEMBER VER MOD GROUP ACCESS ID STATUS 

CCC 01 00 DEPT1 MAI AVAILABLE 



GROUP: DEPT2 TARGET: SYSTST LEVEL: BOTTOM 

LOG ACCESS ID PROMOTION PROMOTION COLLECT 

TYPE PROMOTER PACK ACT DIST TAB ENTRY ID CONTROL EXIT NAME EXIT TYPE NAME 



LOAD LIBADM NO NO 
MSGS FR2 NO NO 
PLI USSET NO YES PRIVATE 



MEMBER VER MOD GROUP ACCESS ID STATUS 
DDD 01 01 DEPT2 FR3 FR3 

****** END OF STATUS LISTING *********************** 



.t..k.l»l..t..>..L.t..'.J..t..l..1..l,.'.>1..l..l..U<.J.J..I..t..l«l. 



Figure 24. Sample Control Status Listing 



The fields are: 



PROJECT INFORMATION 



PROJECT Project name 

ADMINISTRATOR Project administrator ID 

UPDATE IN PROGRESS Yes or no 

DATE Date of activity in national language 

format 

TIME Time of activity in hh:mm 24-hour 

format 
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GROUP INFORMATION 



GROUP 

TARGET 

LEVEL 

TYPE 

PROMOTER 
PACK 
LOG ACT 
DIST TAB 
ENTRY ID 

ACCESS ID CONTROL 



PROMOTION EXIT NAME 



PROMOTION EXIT TYPE 

COLLECT NAME 

MEMBER INFORMATION 
MEMBER 



Group name 

Target group name 

Identifier for the level of a group 
within its hierarchy 

Type name 

Promoter ID 

Packed data indicator (yes or no) 

Activity log indicator (yes or no) 

Distribution table name 

Identification of who can promote an 
undefined member to a controlled 
library 

Type of access allowed (limited, 
open, or private) 

limited only those in the entry ID 
can access the member to 
update it 

open anyone can access the 
member to update it 

private only the user who promotes 
the member into the 
controlled library can 
access the member to update 
it 

Name of exit for performing 
additional operations on member 
before promotion to entry- level 
library 

Promotion exit type (command or 
program) 

Collection name 



Member name 
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VER 
MOD 
GROUP 
ACCESS ID 
STATUS 



Version number 



Modification level 



Group name 

Access ID 

Indicator of member availability for 
update 

AVAILABLE available for update 



PREDEFINED 



LOGON ID 



member has been 
predefined and has not 
yet been promoted into 
a controlled library 

the member has been 
edit -locked by the 
user whose ID is 
specified. No other 
user may promote the 
member until the user 
who edit -locked the 
member promotes or 
frees it. 

If you want to use the data in the control status for special reports, 
you have to know the record layout. The data set name is the name you 
specified in the Control Status Listing panel. The record layout is 
specified in Appendix 8. 



Member Status 



When you select option 3 on the Review Activity and Controls panel, the 
Member Status Review panel (Figure 25) is displayed. 



48 ISPF/PDF for MVS Library Management 



MEMBER STATUS REVIEW 



OPTION ===> 2 



1 - Browse member status 

2 - Print member status 

3 - Write member status to a data set 

ISPF LIBRARY: 



PROJECT ==> ISPFEXAM 

TOP GROUP ===> PROD 

TYPE => * 

MEMBER ==> * 

OUTPUT DATA SET 

DATA SET NAME ===> 



(* for all top groups) 

(* for all types) 

(Name, truncated name, or * allowed) 

(Option 3 only) 



Figure 25. Member Status Review Panel 



You specify the member whose status you want to review. If you specify 
an asterisk (*) for top group, type, and member, you can review the 
status for every member in all top-level groups of the controlled 
library. 

Option 1 causes the status for the specified members to be displayed. 
This display is scrollable. 

Option 2 causes the member status data to be sent to the ISPF list data 
set. You can then obtain a hardcopy printout of the member status data. 

Option 3 causes the member status data to be written on a data set that 
you specify. You specify that data set name where indicated on the 
panel. The data set will be allocated if it does not already exist. 
You can then do what you want with the member status data, such as 
formatting it in different ways for different reports. See Appendix B 
for the record format. 

An example of a printout of a member status listing for project ISPFEXAM 
is given in Figure 26. 
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LIBRARY MEMBER STATUS REVIEW 



PAGE 1 



PROJECT: ISPFEXAM UPDATE IN PROGRESS: NO DATE: 83/11/21 TIME: 14:57 
MEMBERS FOR HIERARCHY: ISPFEXAM. PROD. MSGS 



MEMBER 


VER 
01 


MOD 
00 


GROUP 
PROD 


ACCESS 


ID 


STATUS 


CMSG1 


FR2 




*LOCKED* 


EMSG1 


01 


00 


PROD 


FR1 




AVAILABLE 


EMSG2 






PROD 


MAI 




PREDEFINED 


SMSG1 






PROD 


FR3 




PREDEFINED 


SMSG2 






PROD 


MA2 




PREDEFINED 



MEMBERS FOR HIERARCHY: ISPFEXAM. PROD. PLI 

MEMBER VER MOD GROUP ACCESS ID 



STATUS 



AAA 






PROD 


FR2 


*LOCKED* 


AAA 


01 


00 


SYSTST 


FR2 


AVAILABLE 


BBB 


01 


00 


PROD 


MA2 


AVAILABLE 


CCC 


01 


00 


DEPT1 


MAI 


AVAILABLE 


CCC 






PROD 


MAI 


^LOCKED* 


DDD 


01 


01 


DEPT2 


FR3 


FR3 


DDD 






PROD 


FR3 


BLOCKED* 


DDD 


01 


00 


SYSTST 


FR3 


BLOCKED* 



*********************** END OF STATUS LISTING ********************** 



Figure 26. Sample Member Status Review Listing 



The fields are: 



PROJECT INFORMATION 

PROJECT Project name 

UPDATE IN PROGRESS Yes or no 



DATE 



TIME 



Current date in national language 
format 

Current time in hh:mm 24 -hour format 
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MEMBER INFORMATION 
MEMBER 
VER 
MOD 
GROUP 
ACCESS ID 
STATUS 



Member name 

Version number 

Modification level 

Group name 

Access ID 

Indicator of member availability for update 

AVAILABLE available for update 

PREDEFINED member has been predefined and 

has not yet been promoted into a 
controlled library 

LOGON ID member has been taken out for 
update by the user with the 
specified logon ID 

LOCKED the member can be accessed for 
update only in a lower level of 
the hierarchy. 

If you want to use the data in the member status for special reports, 
you must know the record layout. The data set name is the name you 
specified in the Control Status Listing panel. The record layout is 
specified in Appendix B . 



LIBRARY MAINTENANCE 



Library maintenance involves keeping the libraries and the library 
controls current by adding or deleting libraries or controls when 
necessary. 

To help in maintaining the libraries, you can obtain listings of the 
activity log, control status, and member status. You can browse through 
displays of these listings, get printouts of the listings, or both 
browse and print out the data for which you want a hardcopy listing. 
The listings can be obtained by selecting option 5 from the Library 
Management Utilities panel. 

The tables created for control purposes, such as the distribution table 
and user set, are dynamic. They can be changed as need dictates. All 
panels used to create libraries can also be used to update libraries. 
Hence, the panels used to create libraries and specify controls are the 
panels used to update libraries and controls. However, you must 
deactivate the controls when performing most maintenance functions. You 
can update user sets and member controls when they are active. However, 
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after completing the maintenance, be sure to activate all deactivated 
controls again so that the libraries can be used. 

Library controls can be deleted by selecting option 2 of the Specify 
Library Controls panel. However, to delete library controls, the 
library cannot contain any promoted members. 

A user set can be deleted and a distribution table can be deleted by 
choosing option 2 of the Specify User Set panel and option 2 of the 
Specify Distribution Table panel, respectively. However, the library 
controls that reference the user set or distribution table are not 
automatically deleted. You will have to update those controls. 
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CHAPTER 3. LIBRARY USE 



The controlled libraries are ISPF libraries that are used with the PDF 
tools. There is one important difference, however, in using controlled 
libraries. In order to edit or update a member of a controlled library, 
you must bring that member into an uncontrolled library to work on it. 
When you have finished editing that member, you return it to the 
controlled library by means of the promotion process. 

In this chapter, we will look at the actions taken by a user to: 

• Access a member from a controlled library 

• Promote a member to a controlled library 

• Promote a member from one level to another within a controlled 
library. 

We will continue to use the example in Chapter 2 to illustrate the 
actions. 

You must be careful to have the same project and type for the controlled 
library and the private library (the uncontrolled library) in order to 
access a member from a controlled library for update. 

When you access a member for editing (described in the next section, 
"Accessing a Library Member"), that member becomes edit-locked; that is, 
that member is not available for update by anyone other than you. The 
member is locked under your logon ID, making you the only person who can 
update the member and promote it into the controlled library. The 
member is said to be edit-locked. The member becomes available when you 
promote the member to an entry- level library or free the member. A 
discussion of freeing a member is on page 63. 

There is another type of locked member. If a member is in two or more 
levels of a hierarchy with the same name in all levels, it is locked in 
all of the higher levels and available for updating only from the lowest 
level of the hierarchy in which it appears. For example, if you should 
have a member called MEMBERA in the top -group library of a library 
hierarchy and, also, a more recent copy of MEMBERA in the entry- level 
library, MEMBERA is locked in the top -group library. It can be accessed 
for update from the entry- level library. This ensures that updates to 
the member will always be made to the most recent copy. 
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Accessing a Library Member 



To access a library member from a controlled library for updating, you 
concatenate the library hierarchy to a private library. The most recent 
version of the member is then available for you to edit in your private 
library. 

To access the member, select option 2 (Edit) on the PDF Primary Option 
menu. The Edit Entry panel, Figure 27, is displayed. 



EDIT - ENTRY PANEL 



COMMAND ===> 



ISPF LIBRARY: 

PROJECT ===> ISPFEXAM 

GROUP => FR2 => DEPT1 ==> SYSTST => PROD 

TYPE ===> PLI 

MEMBER => (Blank for member selection list) 

OTHER PARTITIONED OR SEQUENTIAL DATA SET: 
DATA SET NAME ===> 
VOLUME SERIAL ===> (If not cataloged) 

DATA SET PASSWORD => (If password protected) 

PROFILE NAME ==> (Blank defaults to data set type) 

INITIAL MACRO ==> 

MIXED MODE ===> (Specify YES or NO) 

FORMAT NAME => 



Figure 27. Edit Entry Panel 



The project, group, and type fields have already been filled in. You 
will note that the controlled libraries are concatenated to the private 
library in group FR2. DEPT1 is concatenated to FR2, SYSTST to DEPT1, 
and PROD to SYSTST. As you recall, PROD is the top-level group, SYSTST 
the middle- level group, and DEPT1 a bottom- level, or entry- level, group, 

You must select the member and then change it to get it into your 
private library. If you are not authorized to access the member for 
update, you will be told at selection time. If the member is locked, 
you will be told at selection time. The member may be edit -locked, 
meaning that someone else has already accessed the member to update it. 
It may also be locked because you are not selecting the most recent 
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copy. The latter situation can occur if you leave a group out when 
specifying the concatenation. 

As with any ISPF edit operation, there are two ways of selecting the 
member you want to update. 

The first way to select a member is to specify the member name on the 
Edit Entry panel. For example, to select member BBB from the library 
you would specify: 

MEMBER => BBB 

The first occurrence of member BBB is then displayed. 

The second way is to select a member is to leave the member name field 
blank, as in the example above. This results in the display of the 
member list, an example of which is shown in Figure 28. 



EDIT --- ISPFEXAM.FR2.PLI ■ 

COMMAND ===> SCROLL =™> PAGE 

NAME LIB VV.MM CREATED LAST MODIFIED SIZE INIT MOD ID 

AAA 3 01.00 83/07/26 83/07/26 15:13 2 2 FR2 

S BBB 4 01.00 83/07/26 83/07/26 15:15 4 4 MA2 

CCC 2 01.00 83/07/26 83/07/26 15:16 4 4 MAI 

DDD 1 01.00 83/07/27 83/07/27 08:07 2 2 FR3 

**END** 



Figure 28. Sample Member Selection List 



Note: The date is displayed in the national format of the 
language being used. 
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This list shows you all the members that are now available to you in 
your private library. The list also indicates the library in which the 
first occurrence of the member is found, in the column labeled LIB. 
This column contains numbers (1 to 4) that identify the library in which 
a member can be found. These numbers correspond to the four group entry 
fields on the Edit Entry panel. The meanings of the numbers for our 
example are: 

NUMBER FIRST LIBRARY IN WHICH MEMBER IS FOUND 



1 ISPFEXAM.FR2.PLI 

2 ISPFEXAM.DEPT1.PLI 

3 ISPFEXAM . SYSTST . PLI 

4 ISPFEXAM. PROD. PLI 



Selecting a member causes that member to be displayed and to be locked 
in the control file with your ID. For our example, member BBB was 
selected by entering "S M next to BBB on the panel shown above. You can 
then update the selected member. The updated member will be placed in 
your private library. You can then return it to the controlled library 
by promoting it. We will look at promotion in the next section. 

Either way, you get the member from the first library in which it is 
found . 

A member can exist in more than one level of the library hierarchy. 
However, each level in the library structure will have a different form 
of the member. 

Let us illustrate the information in the preceding paragraph with an 
example. Member DDD has been promoted to a middle- level library, group 
SYSTST. It was then obtained, updated, and placed in the private 
library ISPFEXAM .FR2 . PLI . 

We have not yet shown that member DDD is in the middle- level library 
and, if it is, that it is different from the member in the private 
library. To verify that member DDD is in library PLI of group SYSTST, 
we can use the Browse option, option 1 on the PDF Primary Option Menu. 
If the member is in the library, the Browse option displays the contents 
of the member. 

For our example, when you select option 1 on the PDF Primary Option 
Menu, the panel shown in Figure 29 is displayed. 
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BROWSE - ENTRY PANEL 



COMMAND ==> 



ISPF LIBRARY: 

PROJECT ==> ISPFEXAM 

GROUP ===> SYSTST ===> ===> ===> 

TYPE ===> PLI 

MEMBER — => DDD _ (Blank for member selection list) 

OTHER PARTITIONED OR SEQUENTIAL DATA SET: 
DATA SET NAME ==> 
VOLUME SERIAL ==> (If not cataloged) 

DATA SET PASSWORD => (If password protected) 

| MIXED MODE ===> (Specify YES or NO) 

I 

| FORMAT NAME ===> 



Figure 29. Browse Entry Panel 
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The display of member DDD in ISPFEXAM.SYSTST.PLI is shown in Figure 30, 



BROWSE -— ISPFEXAM.SYSTST.PLI (DDD) - 01.01 - LINE 000000 COL 001 080 

COMMAND => _ SCROLL ===> PAGE 

" ♦* " " ' " " " ♦♦ *» " •• •* • " " " " " " •♦ ♦• i Or Ur DA 1 A " " " " " " ** " •* " " " " •♦ " ' v " " " " ' " " " " ♦♦ " " ** " 

FOXX TO CR0NIN AND BACK TO FOXX 

AND THEIR WORTHY OPPONENTS LOST THEIR SOCKS. 
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Figure 30. Browse Display for Member DDD in Private Library 
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Using the Edit option, the display of member DDD in library 
ISPFEXAM.FR2.PLI is shown in Figure 31. 



EDIT --- ISPFEXAM.FR2.PLI(DDD) - 01.02 COLUMNS 001 072 

COMMAND. => _ SCROLL ===> HALF 

000100 FOXX TO CRONIN AND BACK TO FOXX, 

000200 AND THEIR WORTHY OPPONENTS LOST THEIR SOCKS. 

000300 FOXX TO CRONIN AND BACK TO FOXX, 

000400 IT WAS ALMOST AS BAD AS THE CHICKEN POX. 

«wwww>« ,ww. ,., www. ,w> ,w. ,wwww» ,v „<>,.,.,. ,ww. .wv JJUIIUM Ur DAI A « 'WWWWWWWWWWWWWWWWWWWWWW. 



.U.<.JI..l..>.J. 



Figure 31. Edit Display for Member DDD in Middle-Level Library 



Thus, there are two forms of member DDD in two different libraries in 
the hierarchy. The updated member is in the private library. Promoting 
member DDD will put the updated member into the entry-level library, 
replacing what was previously there, and will remove the member from the 
private library. 

Note: LMF does not allow a member to be updated, simultaneously, 
by more than one person. When a member is accessed by means of 
the Edit Entry panel, it is edit -locked; that is, it is marked as 
being "out for update." That member cannot be accessed by any 
other user by means of the Edit Entry panel for the purpose of 
updating and promoting it back to a controlled library until it is 
free; that is, until it is promoted back to the entry- level 
library. However, the user who originally edit -locked the member 
can obtain the member again without first promoting it into the 
controlled library. 

If you attempt to access a member that was not edit-locked with 
your logon ID, the error panel shown in Figure 32 is displayed. 
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- ISPF LIBRARY SERVICES ERROR 

COMMAND ===> 



»t..t..U.'..U.I«1..J-.t<.U*U.t..'..l.»<..t..'..U.t..1„t..t„1„U.J.-t... 



ERROR DESCRIPTION: * 

EDIT LOCK FAILED * 

THE MEMBER IS NOT FREE. * 



INSTRUCTIONS 



* Press ENTER key to proceed with Edit. 

* Enter END command to terminate Edit. 



.•..'..«..t..Vi>l..(..t..l..t. 



Figure 32. ISPF Library Services Error Panel 



If you only want to have the member in your private library and do 
not intend to promote it, press the ENTER key. You will then be 
able to proceed with your changes. If you intend to promote the 
member after you change it, you cannot do so now. You cannot 
promote a member that is not edit -locked with your logon ID. You 
must enter the END command on this panel, and then either wait 
until the member is freed or request that the current owner 
promote the member so it will be available to you. To find the ID 
of the person who edit -locked the member, review the member 
controls (option 8.5.3). 

Promotion To the Controlled Library 

You promote members by using the PDF Move/Copy Utility, PDF option 3.3. 
Two options allow you to promote members: option P promotes a member, 
while option PP promotes a member and prints it. 

When you promote a member to a controlled library from a private 
library, the Move/Copy utility does not know the entry-level library to 
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which you want to move the member. Therefore, you must specify the 
library that will receive the promoted member; that is, the target 
library. The target library must be specified since a member can be 
promoted to any entry- level library from a private library, provided you 
have authority to promote. 

After a successful promotion, the promoted member is deleted from the 
private library. In the event of a system failure, you will be able to 
promote that member again. 

To illustrate promotion of a member from a private library to an 
entry-level library, we will use our example. In the last section, we 
accessed member DDD of the middle-level library PLI . We updated member 
DDD. Now we want to promote it to the entry- level library. For our 
example, the Move/Copy Utility panel is shown in Figure 33. 



MOVE/COPY UTILITY 



OPTION ===> P 



C - Copy data set or member (s) CP - Copy and print 

M - Move data set or member (s) MP - Move and print 

P - Promote data set or member (s) PP - Promote and print 

SPECIFY "FROM" DATA SET BELOW, THEN PRESS ENTER KEY 

FROM ISPF LIBRARY: 

PROJECT => ISPFEXAM 

GROUP ==> FR2 

TYPE ==> PLI 

MEMBER ==> DDD_ (Blank for member list, * for all members) 

FROM OTHER PARTITIONED OR SEQUENTIAL DATA SET: 
DATA SET NAME ===> 
VOLUME SERIAL ===> (If not cataloged) 

DATA SET PASSWORD ==> (If password protected) 



Figure 33. Move/Copy Utility Panel 



If you leave the member name field blank, you will get a member 
selection list. For a discussion of the member selection list, see 
ISPF/PDF for MVS Program Reference . This manual also contains a 
discussion of promoting members with aliases. 
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Since the requested promote operation is from a private library (group 
FR2), the promote utility does not know what the target library is; that 
is, where to promote this member. In this case, the utility asks for 
identification of the target library by displaying a panel requesting 
that information. For our example, the panel requesting the target 
library is shown in Figure 34. 



PROMOTE --- FROM ISPFEXAM.FR2.PLI (DDD) - .-- 

COMMAND =>. 

SPECIFY "TARGET" CONTROLLED LIBRARY BELOW. 

TO ISPF LIBRARY: 

PROJECT ===> ISPFEXAM 

GROUP ===> DEPT1 

TYPE ===> PLI 

MEMBER ==> (Blank unless member is to be renamed) 

ACTION => MOVE (MOVE to copy and delete source 

FREE to only delete source) 

REASON CODE ===> 

PACK DATA ===> (YES, NO, or blank to default to library controls) 



Figure 34. Move/Copy Utility - Target Library Specification Panel 



Three fields in the panel above are new: 

ACTION This field specifies whether a normal promotion of the 
member is to occur, or the member is to be made 
available (freed) for update. The latter action may be 
specified if you do not want to promote the member for 
some reason, but want to make the member available to 
others. The specified actions are: 

MOVE Promotion in which the member is moved to the 
target library and deleted from the private 
library. The member becomes available for 
update; that is, it is no longer locked by 
your logon ID. 
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FREE Make the member available, no longer locked 

by your logon ID. The member is not moved to 
the target library, but is deleted from the 
private library. 

REASON CODE This is a 26-character field that appears in the 

activity log. You can use it for tracking, testing in 
a user exit, or for any other purpose. 

PACK DATA You can use this field to override the library control. 
Leaving this field blank defaults to the packed data 
library control specification. If the data is packed 
(or unpacked) when promoted into an entry- level 
library, it will remain packed (or unpacked) throughout 
each subsequent promotion. 

PACK uses a unique ISPF data compression routine. 
Attempts to access or execute the data outside of PDF 
can cause unpredictable results. See the description 
of the Edit PACK command in ISPF/PDF for MVS Program 
Reference for more information. 

You will be notified by a message on the Move/ Copy Utility panel whether 
the promotion was successful. For a successful promotion, the message 
is: 

MEMBER xxx PROMOTED 
where xxx is the member name. For our example, the message received is: 

MEMBER DDD PROMOTED 
If the promotion is not successful, you will get the message: 

PROMOTE FAILED 

Entering the HELP command will give you additional information on the 
reason for the failure. 

Promotion Within the Controiied Library 

Now that member DDD has been promoted to an entry- level library, we want 
to promote it to the middle- level library from which it was accessed for 
updating. Promotion within a controlled library is accomplished with 
the Move/Copy Utility. The promotion of member DDD to the middle- level 
library is specified as shown in Figure 35 . 
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MOVE/COPY UTILITY • 

OPTION ===> P 

C - Copy data set or member (s) CP - Copy and print 

M - Move data set or member(s) MP - Move and print 

P - Promote data set or member (s) PP - Promote and print 

SPECIFY "FROM" DATA SET BELOW, THEN PRESS ENTER KEY 

FROM ISPF LIBRARY: 

PROJECT ==> ISPFEXAM 

GROUP => DEPT1 

TYPE ==> PLI 

MEMBER ==> DDD _ (BLANK FOR MEMBER LIST, * FOR ALL MEMBERS) 

FROM OTHER PARTITIONED OR SEQUENTIAL DATA SET: 
DATA SET NAME ==> 
VOLUME SERIAL ===> (If not cataloged) 

DATA SET PASSWORD ===> (If password protected) 



Figure 35.' Move/Copy Utility Panel - Promotion into a Middle-Level Library 



In this case, the utility knows the target library, so it does not 
request it. The target library is known from the hierarchical library 
controls that have been set up. The target library must be a library of 
the same type as the one from which the promotion was requested. 

All promotions into a controlled library and within a controlled library 
are performed by the Move/Copy Utility. The only difference is that the 
entry-level library must be specified for promotion to a controlled 
library. The utility requests that information from you when it is 
needed . 

Changing Member Version Numbers 

If a distribution table is used, you may at some point need to change 
the version numbers of the members in your hierarchy. For instance, if 
you have a system of programs that run in three library hierarchies, at 
some point a program that is common to all three hierarchies may have to 
be changed so that there is a different version in each hierarchy. 
Conversely, you might have three different versions of the same program 
in the three library hierarchies, which can be made into a common 
program . 

64 ISPF/PDF for MVS Library Management 



For example, let's say that we have a two- level hierarchy for a set of 
programs that run in each of three environments . 



Project: EXAMPLE 1 
TOPI 



T0P2 



T0P3 



P | | P | | P 

L I I L | | L 

II III II 



B0T1 



B0T2 



B0T3 



The first library hierarchy consists of the entry- level library 
EXAMPLE 1.B0T1.PLI and its target library EXAMPLE 1. TOP 1. PLI . In the 
second library hierarchy, the two groups are top group T0P2 and bottom 
group B0T2. There is a PLI library in each of these groups. Libraries 
EXAMPLE 1.B0T3. PLI and EXAMPLE 1.T0P3. PLI make up the third library 
hierarchy. 

The distribution table could look like this : 



VERSION 


TARGET 


NUMBER 


GROUP 


50 


B0T1 


50 


B0T2 


50 


B0T3 


51 


B0T1 


52 


B0T2 


53 


B0T3 



In this distribution table, all programs common to all three 
environments have version code 50. Programs for the first environment 
only have version code 51. If the program is dependent on the second 
operating system, the version code is 52. Programs that only work in 
the third operating system have version code 53. 
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Changing a Member from One Common Version to Several Different Versions 

In the first case, you would have to change the version numbers of the 
member in all three hierarchies from the version number for common 
pjrograms to the version number for each individual environment. 

To change the version code of a member with a version code of 50 to 
version codes 51, 52, and 53, you must change the version numbers one at 
a time. To change the version codes you must to perform the following 
steps: 

1. Edit the member from the first library hierarchy. Remember to 
concatenate your private library ahead of the controlled libraries 
on the Edit Entry Panel. 

2. Change the version number to the proper one for the environment. In 
the example, we would change the version number to 51. 

3. Use the Move/Copy Utility, PDF option 3.3, to promote the member to 
the desired entry-level library. In this case, you would specify 
the target library to be EXAMPLE 1.B0T1.PLI. 

4. Edit the member from the library hierarchy for the second library 
hierarchy, concatenating those libraries to your private library. 

5. Again, change the version number to the proper one for the library 
hierarchy. This time, we would change the version number to 52. 

6. Use the Move/Copy Utility, PDF option 3.3, to promote the member to 
the desired entry-level library, which would be EXAMPLE 1.B0T2. PL I in 
the example. 

7. Continue to edit -lock the member, change the version number and 
promote the member to the appropriate library until all of the 
members with that name have been changed to the proper version code. 
In this example, we would have to go through the same steps for the 
third environment before we would be finished. 

Changing A Member from Several Different Versions to One Common Version 

In the second case, you would have to change the version numbers of the 
member in all three hierarchies from the version number for each 
individual environment to the version number for common programs. Since 
you cannot promote a member to a library that you did not edit -lock it 
in, you cannot merely change the version number of one of the members. 
The following steps allow you to change the version numbers for programs 
in the individual library hierarchies to the version number for programs 
common to many library hierarchies . 

1. Edit one of the members, concatenating your private library ahead of 
the controlled libraries. You must not start with the member that 
is going to be made common. That is, if the member that is 
currently version 52 in the second library hierarchy is the one that 
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you want to be made common, start with the first or the third 
hierarchy. Save the one you want to keep for last. 

2. Use the Library Utility, PDF option 3.1, to delete the member from 
your private library. 

3. Continue editing the member, saving the member in your private 
library, and deleting it until you have deleted all but one of the 
members with that name. Again, the member you want to keep should 
be the only one left with that name in the library hierarchies 
affected by the distribution table. 

4. Change the version number of the member to the version number for 
common programs. It would be version code 50 in our example. Use 
the Move/Copy Utility, PDF option 3.3, to promote the member to a 
library hierarchy. Because of the distribution table the member 
will be promoted to all of the library hierarchies. For example, if 
you specify EXAMPLE 1 .B0T1 . PLI as the target for the promotion, the 
member is also promoted to EXAMPLE 1.B0T2. PLI and EXAMPLE 1.B0T3. PLI. 
This promotion succeeds because you have edit -locked this member in 
all target libraries. 

These guidelines apply whether you have two groups or fifty groups in 
your distribution table. The same considerations apply for the different 
combinations that could occur if you have programs that are common to 
some library hierarchies, but are different in one or more other library 
hierarchies . 
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APPENDIX A. USER EXIT EXAMPLE 



If you specify a user exit name and user exit type on the Create or 
Update Library Controls panel (see page 21), when you request that a 
member be promoted to a controlled library, the user exit will be taken 
prior to promoting the member. Usually the user exit is specified so 
that you can do some checking, validating, or modifying of the member 
before promoting it. However, you can use the user exit for any purpose 
you want . 

The user exit name PROMCHEK and user exit type COMMAND were specified 
for the CLIST example presented below. This example checks some 
variables. If all checks are good, the promotion takes place. If any 
check fails, the promotion of the member does not take place. 

In the command or program, any, or all, of the ISPF variables can be 
used. 
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PROC 



..T„l„U.^„V-V-^-'«^-'«^-'"^^-'"'«'--'--'«'"^'« , --'« , --'-- , "'"^-^-^-'--'"'--^-^^ 



k***/ 



*/ 
*/. 
*/ 
*/ 



/* 

/* THIS CLIST IS THE 'USER EXIT 1 FOR PROMOTION INTO 

/* ISPFEXAM.DEPT1.PLI 
/* 

ISPEXEC CONTROL ERRORS RETURN 
SET RC = 

ISPEXEC VGET (ZLTPRJ, - 

ZLTGRP, - 

ZLTTYP, - 

ZLTMEM, - 

ZLFPRJ, - 

ZLFGRP, - 

ZLFTYP, - 

ZLFMEM, - 

ZLFDSN, - 

ZLFVOL, - 

ZLFPWD, - 

ZLACT, - 

ZLRCD, - 

ZLPAC) SHARED 



/* 14 VARIABLES 



/' 



.(..I..UUI.. 



.1.-'— :'«'«'«'-*'-» , "'«'- 



/ 



/* THE LIBRARY MANAGEMENT VARIABLES ARE: */ 

/* ZLTPRJ - TO PROJECT NAME */ 

/* ZLTGRP - TO GROUP NAME */ 

/* ZLTTYP - TO TYPE */ 

/* ZLTMEM - TO MEMBER NAME */ 

/* ZLFPRJ - FROM PROJECT NAME */ 

/* ZLFGRP - FROM GROUP NAME */ 

/* ZLFTYP - FROM TYPE */ 

/* ZLFMEM .- FROM MEMBER NAME */ 

/* ZLFDSN - FROM DATA SET NAME */ 

/* ZLFVOL - FROM VOLUME SERIAL */ 

/* ZLFPWD - DATA SET PASSWORD */ 

/* ZLACT - ACTION */ 

/* ZLRCD - REASON CODE */ 

/* ZLPAC - PACK DATA */ 

/* */ 

/* EXAMPLES OF LOGIC WHICH CAN DYNAMICALLY STOP THE */ 

/* PROMOTION PROCESS BY RETURNING A NON-ZERO RETURN CODE */ 

/* */ 
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/* CHECK PROJECT NAME */ 

IF &ZLTPRJ = ISPFPROJ THEN + 

SET &RC = 4 
ELSE + 

% " / 

/* CHECK TYPE IS PLI */ 

DO 

IF &ZLTTYP = PLI THEN + 

SET &RC = 8 
ELSE + 

/* CHECK ACTION IS MOVE */ 

/ 

DO 

IF &ZLACT = MOVE THEN + 

SET &RC = 12 
ELSE + 

/* CHECK FIRST SEVEN CHARACTERS OF REASON CODE */ 

/J.J.J.J.J.J..U.J.J.J.J.J..I.J.J.J.J.J..U.J.X.I..I.AJ..UAJ.J.J.J..L.1.J.J.J..^.U..U.J..I..^^^^^ / 

DO 

IF &SUBSTR(1:7,&ZLRCD) = PROBLEM THEN + 

SET &RC=16 
ELSE + 

/* CHECK IF DATA IS PACKED */ 

DO 

IF &ZLPAC = NO THEN + 

SET &RC = 17 
END 
END 
END 
END 
EXIT CODE(&RC) 
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A return code of indicates that all checks were successful, so the 
member is promoted to the controlled library. If the return code is 
something other than 0, at least one check failed and the member is not 
promoted. You will need CLISTs or programs that specify what actions to 
take for each test failure. 
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APPENDIX B. RECORD FORMATS 



Activity Log 



The format of the records in the activity log data set is 



Member name 
Group name 
Action type 

L - Edit -lock 

M - Move 

F - FREE 
Requester's user id 
Date of this request (national 

language date format) 
Time of this request (hh:mm) 
Time of request in seconds 
Version identifier 
Modification level 
Collection name 
Reason on promote 
Reserved 



char (8) 
char (8) 
char(l) 



char (8) 
char (8) 

char (5) 
char (2) 
char (8) 
char (2) 
char (8) 
char (26) 
char (6) 



Status Listing 



The following format is utilized for all status listing records written 
when the data set options 8.5.2.3 and 8.5.3.3 are selected. Each record 
consists of a sort area and a data area. The sort area has fields 
common to all types of output records. The data area has different 
information depending upon the type of record being written. 
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Data Set Record Format 



SORT AREA 



BYTE FIELD NAME 



1-4 Promote hierarchy number 

5-8 Promote hierarchy level 

9-16 Group name 

17-24 Type name 

25-32 Member name 

33-34 Record type 

35-45 Not currently used 



DESCRIPTION 

Fixed(31) 1 

Fixed (31) 2 

Char(8) 

Char(8) 

Char(8) 

Char (2) 3 

Char(ll) 



DATA AREA 



46-160 Insert a description below Char (115) 



1 Groups are numbered in preorder sequence with top groups in alphabetical order. 
Each group has a number. These numbers are sequential with the exception of 
illegally defined groups, which are numbered 999999. 

2 Hierarchy level indicates the depth of the group within the hierarchy. All top 
groups are on level 1. Groups having top groups as targets are level 2, and so on. 

3 Possible record types are A0=Project record, C0=Group record, 10=Type record, 
80=Member record. 
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Data Area Format For Specific Data Records 



Project Record 
BYTE FIELD. NAME 



46-53 Project name 

54 Blank 

55-62 Project administrator 

63 Blank 

64-71 Updater (blank if not being updated) 

72 Blank 

73-80 Date 

81 Blank 

82-89 Time 

90-160 Blank 



DESCRIPTION 

CHAR (8) 
CHAR(l) 
CHAR (8) 
CHAR(l) 
CHAR (8) 
CHAR(l) 
CHAR (8) 
CHAR(l) 
CHAR (8) 
CHAR (71) 
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Group 


Record 


BYTE 


FIELD NAME 


46-53 


Group name 


54 


Blank 


55-62 


Target group name 


63 


Blank 


64 


Group Position (T=Top gro 



group (both Top group and Bottom 
group) , M=Middle group (not a top 
or a bottom group) , E=Entry group 



DESCRIPTION 

CHAR (8) 
CHAR(l) 
CHAR (8) 
CHAR(l) 

CHAR(l) 



65 



Blank 



66-73 Deactivator (User id, User set 

or blank if active) 

74-160 Blank 



CHAR(l) 

CHAR (8) 
CHAR (87) 
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Type Record 



BYTE 


FIELD NAME 




DESCRIPTION 


46-53 


Type name 


CHAR(8) 


54 


Blank 




CHAR(l) 


55-62 


Promoter ID 




CHAR(8) 


63 


Blank 




CHAR(l) 


64 


Pack (Y=Yes, N=No) 




CHAR(l) 


65 


Blank 




CHAR(l) 


66 


Log activity (Y=Yes, N=No) 




CHAR(l) 


67 


Blank 




CHAR(l) 


68-75 


Distribution table name 




CHAR (8) 


76 


Blank 




CHAR(l) 


77-84 


Type entry ID 




CHAR(8) 


85 


Blank 




CHAR(l) 


86 


Access type (C=No undefined 


members 






L=Limited, 0=0pen, P==Private) 


CHAR(l) 


87 


Blank 




CHAR(l) 


88-95 


Promotion exit name 




CHAR(8) 


96 


Blank 




CHAR(l) 


97 


Promotion exit type (C=Command 






P=Program) 




CHAR(l) 


98 


Blank 




CHAR(l) 


99-106 


Collection name 




CHAR (8) 


107-160 


Blank 




CHAR (54) 
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Member Record 



BYTE 


FIELD NAME 




46-53 


Member name 




54 


Blank 




55-56 


Version number 




57 


Blank 




58-59 


Modification number 




60 


Blank 




61-68 


Group name 




69 


Blank 




70-78 


Access ID (Logon ID, 


Use 



*0PEN*=Access is open, *LOCKED*=Member 
may be available at a lower hierarchy 
level. 

79 Blank 

80-88 Status (Logon ID, User set name, 
available, or predefined) 

89-160 Blank 



DESCRIPTION 

CHAR (8) 
CHAR(l) 
CHAR (2) 
CHAR(l) 
CHAR (2) 
CHAR(l) 
CHAR (8) 
CHAR(l) 

CHAR (9) 
CHAR(l) 

CHAR (9) 
CHAR(72) 
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GLOSSARY 



Access Control. Specifies how 
ownership is determined when an 
undefined member is promoted into an 
entry- level library. There are three 
categories : 

Open anyone can access this member 
to update it. 

Limited only those in the entry ID can 
access this member. 

Private only the user entering this 
member can access it. 

Activity Log. A set of records that 
contain information describing the 
promote and update activities that have 
taken place for members of a library 
hierarchy. 

Authorized Entry ID. Specifies the 
person, or persons, who can promote an 
undefined member to a controlled 
library. It is either the logon ID of 
the person so authorized or the name of 
a user set containing logon IDs of the 
persons so authorized. 

Authorized Promoters. Specifies the 
person, or persons, who can promote a 
member from one level to another within 
a controlled library. It is either the 
logon ID of the person so authorized, or 
the name of a user set containing logon 
IDs of the persons so authorized. 

Bottom Group. A group that is at the 
lowest level of a promotion hierarchy. 
A bottom group is not a target group for 
any other group. 

Collection Name. An identification that 
is specified at the library level by the 
library administrator. It is recorded 
in the activity log whenever a member is 
promoted to that library level. 



Controlled Group. A collection of 
controlled libraries having a common 
project and group name. 

Controlled Library. An ISPF library 
that has been identified as a library to 
which users must have specific authority 
for access for updates and promotion 
activity. 

Controlled Project. A collection of 
controlled groups having a common 
project name. 

Distribution Table. A table containing 
those groups identifying the multiple 
hierarchies that a specified member is 
to be promoted to. Members are promoted 
into multiple hierarchies by means of 
version numbers. 

Edit- Lock. If you edit a member, 
concatenating your private library ahead 
of the controlled library that contains 
the member, the member becomes locked 
under your logon ID. This means that 
you are the only person allowed to edit 
the member until you promote the member 
back into the controlled library. 

Entry- Level Library. A library that is 
associated with the bottom group in a 
promotion hierarchy. When a member is 
promoted to a controlled library, the 
promotion must be into an entry-level 
library. 

Free. A member is free if it is 
available for update. If a member is 
not locked, it is free. If a member is 
edit- locked, it is freed when it is 
promoted. 

When you are promoting a member, if you 
specify the action to be free, the 
promotion does not move the member into 
the controlled library. Free deletes 
the member from the source library and 
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makes it available for update in the 
controlled library. 

Level. Level identifies the position of 
a group within its hierarchical 
structure. It could be 'top 1 , 'bottom', 
or a number for each group, where one 
(1) is the level number for the top 
group . 

Library Administrator. The person, or 
persons, who creates a controlled 
project and specifies controls for the 
groups, libraries, and members 
associated with that project. 

Library Hierarchy. A promotion 
hierarchy in which all the libraries are 
of the same type. 

Locked. A locked member is unavailable 
for update. There are two kinds of 
members that are locked. 

• A member is locked if there is a 
member with the same name lower in 
the hierarchy. For example, if you 
have MEMBERA in the top group 
library of a library hierarchy, and 
a more recent copy in the entry 
level library, then MEMBERA is 
locked in the top group library. 
This ensures that anyone updating 
the member will get the most recent 
copy. 

• A member is locked if it is being 
edited. If you edit a member, 
concatenating your private library 
ahead of the controlled library that 
contains the member, the member 
becomes locked under your logon ID . 
This means that you are the only 
person allowed to edit the member, 
until you promote the member back 
into the controlled library. 



Promote. The action by which a member 
is moved into or within a controlled 
library structure. 

Promotion Hierarchy. An ordered set of 
related controlled libraries that a 
member is promoted through during a 
development or maintenance process. For 
each group, the library administrator 
specifies the hierarchy. 

Target Group. The destination group 
of a member being promoted from a 
controlled group. The target group must 
be a controlled group. 

Top Group. A group at the highest 
level of a promotion hierarchy. A top 
group has no target group. 

Undefined Member. A member that does 
not exist in a controlled library or 
does not have member controls defined. 

User Exit Name. The name of an 
optional function, written by an 
installation, to do additional 
validation on a member being promoted 
into a controlled library. 

User Exit Type. Indicates whether the 
user exit is a command or a program. 

User Set. A list of logon IDs for 
those people who are to be authorized to 
promote members, or to have access to 
particular library members or library 
controls. There can be more than one 
user set. Each user set in a project 
has its own name. 

Version Number. A number assigned to 
a member by the library administrator 
and assigned by the program developer. 
The number can associate the member with 
a particular promotion hierarchy through 
the use of distribution tables . 
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